Welcome to osgEarth!¶
osgEarth is a 3D mapping SDK for OpenSceneGraph.
- Get a 2D or 3D map up and running quickly and easily using one simple XML file
- Visualize massive amounts of imagery, elevation data, and vector features
- Use open-standards map data services like WMS, TMS, and GeoTIFF
- Work locally or over the Internet
- Develop applications using a full-featured C++11 API
Let’s get started!
Installing osgEarth¶
Building osgEarth¶
The documentation here is focused on Windows.
Building with vcpkg¶
vcpkg is an extremely useful package manager. It works on Windows, Linux and MacOS but for this guide we will focus on Windows.
Step 1 - Configure vcpkg
First, download and bootstrap vcpkg following the instructions on the page.
Next install the dependencies required to build a fully functional osgEarth. This example assume s 64-bit Windows build; you can alter that to correspond to your platform/architecture of choice.
Install the required dependencies:
vcpkg install osg:x64-windows gdal:x64-windows curl:x64-windows
For full functionality, you can install optional dependences as well:
vcpkg install sqlite3:x64-windows protobuf:x64-windows geos:x64-windows blend2d:x64-windows webp:x64-windows basisu:x64-windows draco:x64-windows libzip:x64-windows
This will take awhile the first time you run it as this pulls down lots of dependencies, so go get a cup of coffee.
Once all the dependencies are built, you’ll need to actually build osgEarth.
Step 2 - Clone the repository
Pull down the source from GitHub and create a build folder for your out-of-source build. We always recommend doing an out-of-source build to avoid problems down the road!
git clone https://github.com/gwaldron/osgearth.git
mkdir build
Step 3 - Configure CMake
vcpkg provides a CMake toolchain file that helps osgEarth find all of its dependencies.
Note: You’ll need to specify a different build directory based on your build configuration (Release, RelWIthDebInfo, Debug) and specify the build type using -DCMAKE_BUILD_TYPE. This is because some dependencies of osgEarth don’t pick up both debug and release versions without specifying the build type. Hopefully this will be fixed in future CMake versions.
Most developers will use a RelWithDebInfo build, like so:
cmake -S osgearth -B build -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DWIN32_USE_MP=ON -DCMAKE_INSTALL_PREFIX=[installroot] -DCMAKE_TOOLCHAIN_FILE=[vcpkgroot]\scripts\buildsystems\vcpkg.cmake
Step 4 - Build and install osgEarth
You can build and install osgEarth on the command line using CMake or you can open up the Visual Studio solution and build it from there.
cmake --build build --target INSTALL --config RelWithDebInfo
Step 5 - Set up your runtime environment
You’ll need to make sure that the vcpkg dependencies and osgEarth are in your path:
set PATH=%PATH%;c:\vcpkg\installed\x64-windows\bin
set PATH=%PATH%;c:\vcpkg\installed\x64-windows\tools\osg
set PATH=%PATH%;[installroot]
Building for OpenGL CORE Profile¶
You may wish to build osgEarth with support for the OpenGL CORE profile. In fact is a requirement for some platforms including Apple OSX and VMWare. Doing to requires that you first build OpenSceneGraph with CORE profile support. The OpenSceneGraph dependency in vcpkg does NOT have GLCORE support (at the time of this writing) so you will have to build it yourself.
Build OpenSceneGraph for GLCORE¶
- First, download the GL CORE include files from Khronos and place them somewhere on your system. We’ll call this the GLCORE folder.
- In CMake, set the
OPENGL_PROFILEproperty to “GLCORE”. - In CMake, set the
GLCORE_GLCOREARB_HEADERproperty to the location of the GL folder you downloaded from Khronos. For example, if you include file is atC:\glcore\GL\glcorearb.hyou should set this property toC:\glcore. - In CMake, set the following properties to
ON:OSG_GL3_AVAILABLE
- In CMake, set the following properties to
OFF:OSG_GL1_AVAILABLEOSG_GL2_AVAILABLEOSG_GLES1_AVAILABLEOSG_GLES2_AVAILABLEOSG_GL_DISPLAYLISTS_AVAILABLEOSG_GL_FIXED_FUNCTION_AVAILABLEOSG_GL_MATRICES_AVAILABLEOSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLEOSG_GL_VERTEX_FUNCS_AVAILABLE
- Configure and build OpenSceneGraph.
Build osgEarth for GLCORE¶
Now that you have OSG built with GLCORE support, time to build osgEarth.
- In CMake, set the
OSGEARTH_GLCORE_INCLUDE_DIRproperty to the same folder holding the Khronos include files (the same value of theGLCORE_GLCOREARB_HEADERin your OSG build). - Configure and build osgEarth.
Test you build by running this on the command line (Windows)
set OSG_GL_CONTEXT_VERSION=4.6
osgearth_version --caps
If all went well, it should report “Core Profile = yes”.
You can disable the CORE profile and select a compatibility profile by setting a profile mask like so
set OSG_GL_CONTEXT_PROFILE_MASK=1
The context version and profile mask are also settable via the osg::DisplaySettings class in the OpenSceneGraph API.
Tips for VMware Users¶
Running osgEarth in a virtual machine environment can be tricky since they usually don’t have direct access to the graphics hardware by default. If you are having trouble you can try these tips.
First, build OSG and osgEarth for GL CORE profile (as above).
Next, assess the situation with a capabilities check:
osgearth_version --caps
The output will look something like this:
GPU Vendor: WMware, Inc.
GPU Renderer Gallium 0.3 on llvmpipe
GL/Driver Version: 1.2 Mesa 11.2.0
If is reports a Mesa driver, and the version is less than 3.3, you will need to configure a couple environment variables to move forward (Windows):
set OSG_GL_CONTEXT_VERSION=3.3
set MESA_GL_VERSION_OVERRIDE=3.3
osgearth_version --caps
Good luck!
The Earth File¶
osgEarth uses the familiar Map/Layer paradigm for organizing data. The Map is comprised of a collection of layers. The renderer draws each visible layer one after the next, from bottom to top, to display the final scene. You can see all the different layer types here.
An Earth File is an XML file that describes the contents of a Map in osgEarth.
My First Earth File¶
Here is a very simple earth file that you can find in the tests folder of the repository:
<Map name="Hello, World">
<GDALImage name="World imagery">
<url>../data/world.tif</url>
</GDALImage>
</Map>
This map contains one layer that points to a local GeoTIFF file. In this case, the location is relative to the location of the earth file itself. You can see this map by running one of the osgEarth command line tools:
osgearth_toc simple.earth
That’s it! It is that easy to get a map up and running.
Using Multiple Layers¶
You can add as many layers to your Map as you like. Here’s an example called hires-inset.earth :
<Map name="Hello, World">
<!-- Worldwide image -->
<GDALImage name="World">
<url>../data/world.tif</url>
</GDALImage>
<!-- Higher resolution inset of Boston -->
<GDALImage name="Boston">
<url>../data/boston-inset-wgs84.tif</url>
</GDALImage>
<!-- Higher resolution inset of New York City -->
<GDALImage name="New York">
<url>../data/nyc-inset-wgs84.tif</url>
</GDALImage>
</Map>
In this case, osgEarth will draw the “World” layer first, followed by “Boston” and finally “New York” on top. We also interspersed some XML comments in there.
Adding Terrain Elevation Data¶
Now let’s add some height field data, also knows as a DEM or Digital Elevation Model:
<Map name="ReadyMap">
<TMSImage name="ReadyMap 15m Imagery">
<url>http://readymap.org/readymap/tiles/1.0.0/7/</url>
</TMSImage>
<TMSElevation name="ReadyMap 90m Elevation">
<url>http://readymap.org/readymap/tiles/1.0.0/116/</url>
<vdatum>egm96</vdatum>
</TMSElevation>
<Viewpoints>
<Viewpoint name="San Francisco, California">
<heading>10/heading>
<height>4500.0</height>
<lat>37.5581</lat>
<long>-122.334</long>
<pitch>-34</pitch>
<range>78000</range>
</Viewpoint>
</Viewpoints>
</Map>
A couple things going on here: first we see a TMSImage layer that loads imagery from a Tile Map Service layer over the Internet. Then we have some 90m digital elevation data coming from the same server.
Finally you can see a Viewpoints layer. This is not a visible layer at all! Instead if stores data - in this case, a set of pre-set viewpoints the user can navigate to. osgEarth stores all kinds of data as layers, not all of it visible. Non-visible layers can occur anywhere in the map. Their order or appearance does not matter.
Drawing Vector Features¶
Finally, let’s look at some vector feature data. This is GIS data in the form of points, lines, and polygons. osgEarth has various methods of displaying this data, but let’s keep it simple for now. You can find this one in feature_rasterize.earth :
<Map name="Rasterize Vectors">
<xi:include href="readymap_imagery.xml"/>
<OGRFeatures name="world-data">
<url>../data/world.shp</url>
</OGRFeatures>
<FeatureImage name="Countries" opacity="0.75">
<features>world-data</features>
<styles>
<style type="text/css">
default {
fill: #ff7700;
stroke: #ffff00;
stroke-width: 5km;
}
</style>
</styles>
</FeatureImage>
</Map>
First, we see the use of <xi:include>, a handy XML directive to include another XML file inline. We’re using this to get our imagery.
Next is the OGRFeatures layer. This is a data layer - it won’t be rendered directly - but rather it just points to an ESRI Shapefile we have stored locally.
Finally, the FeatureImage layer points at the data layer and describes how to draw it using a StyleSheet.
More Examples¶
Please look in the tests folder of the repository for lots of examples of earth files. They range from very simple to quite complex and cover a wide range of the available functionality in osgEarth!
Working with Data¶
osgEarth can load many different open standard data formats of imagery, elevation data, and vector features. Read on for tips on preparing your data to get the best results.
Preparing your Data¶
osgEarth needs to chop the source data up into grids of “tiles” for display. You can usually load data directly from source with no pre-processing, but if the data is not optimized, it might be slow! So a little pre-processing is usually a good idea when using large datasets.
Load you data directly first. If it’s fast enough, you are good to go! Otherwise, here are some tips to optimize your data for tiled access. There are two ways to approach it: optimizing a GeoTIFF, or building tilesets. We will also discuss how to combine a folder full of data into a single layer for use in osgEarth.
Optimizing a GeoTIFF¶
GeoTIFF is the most common format for local imagery or elevation data. Here are some steps you can take to speed up osgEarth’s access to GeoTIFFs.
Reproject your imagery¶
osgEarth will reproject your data on-the-fly if it does not have the necessary coordinate system. For instance, if you are trying to view a UTM image on a geodetic globe (epsg:4326), osgEarth needs to do that conversion on the fly – but doing it offline beforehand will be faster.
You can use any tool you want to reproject your data such as GDAL, Global Mapper or ArcGIS.
For example, to reproject a UTM image to geodetic using gdal_warp:
gdalwarp -t_srs epsg:4326 my_utm_image.tif my_wgs84_image.tif
Build internal tiles¶
Typically formats such as GeoTiff store their pixel data in scanlines. However, using a tiled dataset will be more efficient for osgEarth because of how it uses tiles internally.
To create a tiled GeoTiff using gdal_translate, issue the following command:
gdal_translate -of GTiff -co TILED=YES input.tif output.tif
Take it a step further and use compression to save space. You can use internal JPEG compression if your data contains no transparency:
gdal_translate -of GTiff -co TILED=YES -co COMPRESS=JPG input.tif output.tif
Build overviews¶
Adding overviews (also called ‘’pyramids’’ or ‘’rsets’’) can sometimes increase the performance of a large data source in osgEarth. You can use the gdaladdo utility to add overviews to a dataset:
gdaladdo -r average myimage.tif 2 4 8 16
Spatial indexing for feature data¶
Large vector feature datasets (e.g., shapefiles) will benefit greatly from a spatial index. Using the ogrinfo tool (included with GDAL/OGR binary distributions) you can create a spatial index for your vector data like so:
ogrinfo -sql "CREATE SPATIAL INDEX ON myfile" myfile.shp
For shapefiles, this will generate a “.qix” file that contains the spatial index information.
Building Tilesets¶
Pre-tiling your imagery can speed up load time dramatically, especially over the network. In fact, if you want to serve your data over the network, this is the only way!
osgearth_conv is a low-level conversion tool that comes with osgEarth. One useful application of the tool is tile up a large GeoTIFF (or other input) in a tiled format. Note: this approach only works with drivers that support writing (MBTiles, TMS).
To make a portable MBTiles file:
osgearth_conv --in driver GDALImage --in url myLargeFile.tif
--out driver MBTilesImage --out filename myData.mbtiles
--out format jpg
If you want to serve tiles from a web server, use TMS:
osgearth_conv --in driver GDALImage --in url myLargeData.tif
--out driver TMSImage --out url myLargeData/tms.xml
--out format jpg
That will yield a folder (called “myLargeData” in this case) that you can deploy on the web behind any standard web server like Apache.
Tip: The jpg format does NOT support transparency. If your data was an alpha channel, use png instead.
Just type osgearth_conv for a full list of options. The --in and --out options correspond directly to properties you would normally include in an Earth file.
Loading a Directory of Files¶
Sometimes the data you have will consist of lots of individual files that make up a single dataset. DTED elevation data is a common example of this. Instead of loading each individual file into osgEarth as a separate layer, it is best to combine them into one “virtual” dataset.
Use the GDAL gdalbuildvrt utility to create a VRT. A VRT is a “virtual format” that combines multiple files into a single data source.
Say you have a folder full of “.dt1” files. You can create a single layer like so:
gdalbuildvrt output.vrt *.dt1
Now you can just load output.vrt directly in osgEarth, like so:
<GDALElevation name="My DTED data">
<url>output.vrt</url>
<vdatum>egm96</vdatum>
</GDALElevation>
Where to Find Data¶
Help us add useful sources of freely available data to this list. Always check on attribution and distribution requirements from the provider when using 3rd party data!
Raster data
- ReadyMap.org - 15m imagery, 90m elevation, and street tiles for osgEarth developers. Free for development and demo purposes only.
- USGS National Map - Elevation, orthoimagery, hydrography, geographic names, boundaries, transportation, structures, and land cover products for the US.
- NASA BlueMarble - NASA’s whole-earth imagery (including topography and bathymetry maps)
- Natural Earth - Free vector and raster map data at various scales
- Bing Maps - Microsoft’s worldwide imagery and map data ($)
Elevation data
- CGIAR - World 90m elevation data derived from SRTM and ETOPO (CGIAR European mirror)
- GEBCO - General Bathymetry Chart of the Oceans
Feature data
- OpenStreetMap - Worldwide, community-sources street and land use data (vectors and rasterized tiles)
- Natural Earth - Free vector and raster map data at various scales
- DIVA-GIS - Free low-resolution vector data for any country
osgEarth Layers¶
These are the public layer types native to osgEarth.
Imagery¶
| Earth File | API class | Description |
|---|---|---|
| ArcGISServerImage | ArcGISServerImageLayer | Connects to an ESRI ArcGIS Server instance |
| ArcGISTilePackageImage | ArcGISTilePackageImageLayer | Reads an ESRI ArcGIS Tile Package |
| BingImage | BingImageLayer | Connects to Microsoft Bing service. License key required |
| CesiumIonImage | CesiumIonImageLayer | Connects to a Cesium Ion server instance. Key required |
| CompositeImage | CompositeImageLayer | Combines multiple image layers into a single map layer |
| ContourMap | ContourMapLayer | Renders a colored representation of the elevation data in the map |
| GDALImage | GDALImageLayer | Loads any imagery format supported by the GDAL library, including GeoTIFF |
| GDALDEM | GDALDEMLayer | Renders various rasterized shaded elevation maps |
| MBTilesImage | MBTilesImageLayer | Reads imagery tiles from an MBTiles (MapBox Tiles) database file |
| TMSImage | TMSImageLayer | Connects to a TMS (TileMapService) data source |
| WMSImage | WMSImageLayer | Connects to an OGC Web Map Service server |
| XYZImage | XYZImageLayer | Reads imagery tiles in standard XYZ format (no metadata) |
Terrain Elevation¶
| Earth File | API Class | Description |
|---|---|---|
| FlattenedElevation | FlatteningLayer | Alters elevation data to flatten it to a specific elevation value; useful for flattening a region where you intend to place a site model |
| BingElevation | BingElevationLayer | Connects to Microsoft Bing elevation service. License key required |
| CompositeElevation | CompositeElevationLayer | Combines multiple elevation layers into a single map layer |
| GDALElevation | GDALElevationLayer | Loads any elevation format supported by the GDAL library, including GeoTIFF |
| MBTilesElevation | MBTilesElevationLayer | Reads elevation data stored in an MBTiles (MapBox Tiles) database file |
| TMSElevation | TMSElevationLayer | Connects to an OSGeo Tile Map Service data source (locally or networked) |
| XYZElevation | XYZElevationLayer | Reads elevation tiles in standard XYZ format (no metadata) |
Vector Features¶
| Earth File | API Class | Description |
|---|---|---|
| FeatureImage | FeatureImageLayer | Rasterizes vector data into an image layer |
| FeatureModel | FeatureModelLayer | Renders vector data as OpenSceneGraph geometry |
| TiledFeatureModel | TiledFeatureModelLayer | Like a FeatureModel layer, but optimized for pre-tiled vector datasets |
Miscellaneous¶
| Earth File | API Class | Description |
|---|---|---|
| Annotations | AnnotationLayer | Holds a collection of annotation elements (like text labels, place nodes, or features) |
| Debug | DebugImageLayer | Renders metadata about each rendered map tile |
| GeodeticGraticule | GeodeticGraticuleLayer | Display a simple latitude/longitude graticule |
| MGRSGraticule | MGRSGraticuleLayer | Displays a simple MGRS graticule with labels |
| Model | ModelLayer | Loads and displays an external 3D model at a map location |
| Ocean | SimpleOceanLayer | Renders a very simple ocean surface (requires the map to have bathymetry data) |
| Sky | SimpleSkyLayer | Renders a sky model with realistic lighting and shading |
| TerrainConstraint | TerrainConstraintLayer | Alters the triangulation of the terrain skin to incorporate vector data; e.g., to represent ridgelines, coastlines, or to cut out an area where a custom terrain model will go |
| ThreeDTiles | ThreeDTilesLayer | Displays a 3D-Tiles dataset |
| UTMGraticule | UTMGraticuleLayer | Displays a simple UTM graticule |
| Video | VideoLayer | Renders various video formats to a layer (using FFMPEG) |
| Viewpoints | ViewpointsLayer | Pre-set viewpoints that a viewer application can display for the user |
| Wind | WindLayer | Incorporates a wind model (needs other layers that can use the data) |
Feature Sources¶
| Earth File | API Class | Description |
|---|---|---|
| MVTFeatures | MVTFeatureSource | Mapnik Vector Tiles specification |
| OGRFeatures | OGRFeatureSource | Uses a GDAL/OGR vector driver to read feature data. This is the most common feature source for reading local data (e.g., ESRI Shapefile) |
| TFSFeatures | TFSFeatureSource | Reads vector features from a server according to the Tiled Feature Service specification (osgEarth proprietary) |
| WFSFeatures | WFSFeatureSource | OGC Web Feature Service specification (limited implementation) |
| XYZFeatures | XZYFeatureSource | Generic specification for reading tiled vector data from a server |
FAQ¶
Using the API¶
How do I place a 3D model on the map?¶
The osgEarth::GeoTransform class inherits from osg::Transform and will convert map coordinates into OSG world coordinates for you. Place an object at a geospatial position like this:
GeoTransform* xform = new GeoTransform();
GeoPoint point(srs, -121.0, 34.0, 1000.0);
xform->setPosition(point);
If you want your object to automatically clamp to the terrain surface, assign a terrain and leave off the altitude:
GeoTransform* xform = new GeoTransform();
xform->setTerrain(mapNode->getTerrain());
GeoPoint point(srs, -121.0, 34.0);
xform->setPosition(point);
Why does my model have no texture or lighting?¶
Everything under an osgEarth scene graph is rendered with shaders. So, when using your own models (or creating geometry by hand) you need to create shader components in order for them to render properly.
osgEarth has a built-in shader generator for this purpose. Run the shader generator on your node like so:
osgEarth::Registry::shaderGenerator().run( myNode );
After that, your node will contain shader snippets that allows osgEarth to render it properly and for it to work with other osgEarth features like sky lighting.
Why are my Lines or Annotations not rendering?¶
Lines render using a shader that requires some initial state to be set. You can apply this state to your top-level camera (or anywhere else above the geometry) like so:
#include <osgEarth/GLUtils>
...
GLUtils::setGlobalDefaults(camera->getOrCreateStateSet());
For Annotations (FeatureNodes, PlaceNodes, etc.) best practice is to place an Annotation node as a descendant of the MapNode in your scene graph. You can also add them to an AnnotationLayer and add that layer to the Map.
Annotations need access to the MapNode in order to render properly. If you cannot place them under the MapNode, you will have to manually install a few things to make them work:
#include <osgEarth/CullingUtils>
#include <osgEarth/GLUtils>
...
// Manully assign the MapNode to your annotation
annotationNode->setMapNode(mapNode);
// In some group above the annotation, install this callback
group->addCullCallback(new InstallViewportSizeUniform());
// In some group above the annotation, set the GL defaults
GLUtils::setGlobalDefaults(group->getOrCreateStateSet());
Again: MapNode does all this automatically so this is only necessary if you do not place your annotations as descendants of the MapNode.
Text annotations (LabelNode, PlaceNode) are not rendering. Why?¶
Rendering text requires that you disable OSG’s small-feature culling like so:
view->getCamera()->setSmallFeatureCullingPixelSize(-1.0f);
Note: you must do this for each camera.
Community and Support¶
What is the best practice for using GitHub?¶
The best way to work with the osgEarth repository is to make your own clone on GitHub and to work from that clone. Why not work directly against the main repository? You can, but if you need to make changes, bug fixes, etc., you will need your own clone in order to issue Pull Requests.
- Create your own GitHub account and log in.
- Clone the osgEarth repo.
- Work from your clone. Sync it to the main repository periodically to get the latest changes.
How do I submit changes to osgEarth?¶
We accept contributions and bug fixes through GitHub’s Pull Request mechanism.
First you need your own GitHub account and a fork of the repo (see above). Next, follow these guidelines:
- Create a branch in which to make your changes.
- Make the change.
- Issue a pull request against the main osgEarth repository.
- We will review the PR for inclusion.
If we decide NOT to include your submission, you can still keep it in our cloned repository and use it yourself. Doing so maintains compliance with the osgEarth license since your changes are still available to the public - even if they are not merged into the master repository.
Can I hire someone to help me with osgEarth?¶
Of course! We at Pelican Mapping are in the business of supporting users of the osgEarth SDK and are available for contracting, training, and integration services. The easiest way to get in touch with us is through our web site contact form.
Release Notes¶
Version 3.1 (December 2020)¶
As of this release, osgEarth requires C++11.
GEOS: We transitioned from the GEOS C++ API to the C API for stability reasons. If you see GEOS compile/linker errors, this is likely the reason and you should make sure to link with the C library from now on. (GEOS is an optional dependency that enables some feature processing operations.)
Release Highlights:
- New
TerrainConstraintLayerfor masking and custom terrain tessellation. Please seeconstraints.earthfor sample applications. This replaces and extends the oldMaskLayertype. - New
LERCImageLayer(ESRI format) - New
ArcGISTilePackageElevationLayer - New
ArcGISServerElevationLayer - New
DebugImageLayershow_tessellationproperty to display the terrain mesh; handy for visualizing constraints created with the newTerrainConstraintLayer - Map-wide default texture compression setting allows you to enable automatic texture compression in the terrain options section of your earth file
- SONAME for Linux builds is now properly used. This was preventing ABI stability for some package managers.
osgearth_convsupports a geocell index (--index) that can greatly increase the performance of a large tiling operation by implementing a gridded spatial index.- New
SelectExtentToolfor drawing a bounding box on the map and firing a callback. - XYZ layers now support the {-y} notation for Y inversion, a common notation used in web mapping URLs
- Write support for
TMSElevationLayer - Improved task cancellation support throughout. Task cancellation occurs when the results of data-loading task are no longer required (because the camera moved) and we want to cut short the operation.
- Improved polygon tessellation (fixes various edge cases)
- Faster and better vector rasterization using the excellent
Blend2Dlibrary (optional dependency)Transitioned to the GEOS C API for stability - Improved parallelization for some drivers
- Mutex contention analysis in Tracy - helps us identify and mitigate contention to improve parallelization
- Normalized on C++11 threading primitives, almost completely removing the dependency on OpenThreads
- Various speed improvements and bug fixes
- Simplified CMake configuration process
- Support for GDAL 3.1 (mostly - see the spherical mercator note in SRS.cpp)
- Refreshed the documentation site
- GitHub actions for CI on Linux, Windows, and MacOS
Version 3.0 (June 2020)¶
- Layer API overhaul - no more “Options/Config” structures; no more “drivers”
- Namespace overhaul - rolled Util/Features/Symbology/Annotation into the core
- ImGui integration - user intefaces - eventual replacement for “Controls”
- CompositeElevation/Image/LandCover Layers
- GrassLayer (splatting subsystem)
- Powerline Layer
- Wind Layer - add winds that will affect the GrassLayer
- Decal Layers - add geospatial decals to the terrain
- TiledFeatureModelLayer - fast feature rendering for pre-tiles data
- Arbitrary region invalidation and refresh for terrain engine
- Geocoder (OGR - optional build)
- LandCoverLayer - new fractal refinement
- 3D-Tiles Layer
- glTF support (partial, for 3D-Tiles)
- Cesium Ion Layer
- GDALDEM Layer - hillside shading, etc.
- NetworkMonitor tool
- WEBP loader - fast compressed imagery
- BASIS support - image compression
- DRACO support (GLTF) - geometry compression
- Support for >2GB ZIP files (new OSG ZIP plugin)
- Tracy integration - profiling
- Better error reporting infrastructure
- Performance improvements & bug fixes galore
- New documentation structure
Version 2.10 (November 2018)¶
- REX terrain engine promoted to default. Old MP engine is now in legacy support mode.
- Removed the osgEarthQt nodekit from the SDK, along with all Qt examples
- Cleanup of the internal serialization architecture (i.e. osgEarth::Config)
- Compatibility with OSG 3.6.x release/branch
- GL3 and GLCORE profile support
- VirtualProgram performance improvements
- New LineDrawable and PointDrawable classes for cross-GL-profile support
- Better progress/cancelation handling throughout the SDK, including feature subsystem
- Prototype support for ECI reference frames
- Support for “new” osgText implementation in VirtualProgram framework
- New ClusterNode utility class for clustering proximite objects
- Removed deprecations: MaskNode, Profiler, StateSetLOD, TileKeyDataStore, WrapperLayer, MarkerResource, MarkerSymbol, StencilVolumeNode, TritonNode, AnnotationEvents, PolyhedralLineOfSight, some CullingUtils objects
Version 2.9 (February 2018)¶
- New “REX” terrain engine that supports random access tile loading, terrain morphing, faster add/remove
- New Map/Layer architecture to begin standardizing “everything is a layer” approach
- Per-layer shaders, configuration from earth file (rex only)
- Experimental screen-space GPU lines
- Better support for GLCORE, GL 3.3+, and VAOs
- Transition several Extension/etc. to Layers (AnnotationLayer, MGRSGraticule, FeatureModelLayer, SimpleOceanLayer)
- Reworked the mask generate for REX to support skirts
- Synchronous pre-loading of first-LOD terrain data
- GeoTransform node, Annotations self-discover terrain (don’t need to pass in MapNode anymore)
- Experimental FlatteningLayer to flatten the terrain based on feature data
- Combine multiple shaders in a single file/string with [break]
- New ViewFitter class fits to view to a set of points
- Refactored splatting into SplatLayer, GroundCoverLayer
- New improved ephemeris calculator for sun position
- New PagedNode class for easier paging
- Support new OSG 3.5.8 text implementation
- Support GEOS 3.6+
- Added core LandCover/LandCoverLayer classes for classification data
- Added Future/Promise construct for asynchronous operations
- Re-written MGRS, UTM and GARS graticules
- Lots of bug fixes
Version 2.8 (September 2016)¶
- Disabled feature tessellation tiling in BuildGeometryFilter unless max_polygon_tiling_angle is explicitly set. Cropping code was causing issues especially around the poles. Need to come up with a more general solution in the future.
- Better support for osg::Fog in VirtualPrograms with FogEffect. Implemented multiple fog modes.
- Always applying min_range and max_range in MPGeometry to prevent uniform leakage.
- Proper support for centroid clamping for MultiPolygons.
- New requirement to call open() on TileSources and Layers when creating at runtime. This lets you explicitly get the Status of a layer and report errors to users.
- Fixes to EGM96 vertical datum grid.
- BUILD_OSGEARTH_EXAMPLES cmake option for disabling building examples.
- Added nearest sampling support for heightfields
- New feature_join for adding attributes from intersecting
- osgearth_deformation demo
- Scatter filter support for pointsets. Simply places models at each point in the PointSet.
- Performance optimizations when discarding features in javascript style selectors when returning null styles
- Feature geometry caching support
- New min_expiry_frames and min_expiry_time options to TerrainOptions.
- Proper createTile implementation for Rex engine.
- RocksDB cache plugin.
- New osgearth_server application (based on Poco networking libraries). Serve up osgEarth tiles rendered on the GPU to your favorite web mapping tools like Leaflet, OpenLayers and Cesium!
- Packager now supports writing to MBTiles
- New osgearth_skyview example for drawing an “inside out” earth. Turns out osgearth is a great photosphere viewer!
- Experimental WinInet support to replace CURL. New osgearth_http test app.
- Upgraded duktape to version 1.4.0
- Memory usage testing support (osgearth_viewer –monitor to enable)
- New osgearth_3pv utility application.
- Better support for pretiled datasets like TFS and Mapnik Vector Tiles in FeatureRasterSource (and agglite driver)
- Better support for node tethering in EarthManipulator
- Doxygen support
- New openstreetmap vector tiles demos (openstreetmap_buildings.earth and openstreetmap_full.earth)
- Support for Mapnik Vector Tiles datasets
- Fixed improper inversion of y tilekey in FeatureModelGraph and updated all drivers.
- CURLOPT_ENCODING support. If you’ve built curl against zlib, proper HTTP headers for gzip and deflate will be added and automatically decompressed.
- New osgearth_splat example
- New osgEarthSplat NodeKit
- New “template” plugin based on NLTemplate that allows you to write templatized earth files
- Support for xi:include in earth files
- Minimum OpenSceneGraph version is 3.4.0
- Removed MINIZIP dependency
- New Triton and Silverlining NodeKits
- New feature_elevation driver that produces features from
- New raster to feature driver for turning rasters to features
- 330 compatibiity default shader version for GLSL
- Normal mapping integrated into MP, removed normal map extension.
- TravisCI and Coverity support
Version 2.7 (July 2015)¶
- New ObjectIndex system for picking and selection
- New RTT-based picker that works for all geometry including GPU-modified geometry
- Extensions - modular code for extending the capabilities of osgEarth
- New procedural texture splatting extension
- Upgraded ShaderLoader for better modularization of VirtualProgram code
- New “elevation smoothing” property to MP terrain engine
- New support for default MapNodeOptions
- Logarithmic depth buffer lets you extend your near and far planes
- Better Triton and Silverlining support
- Overhaul of the elevation compositing engine and ElevationQuery utility
- New Raster Feature driver lets you generate features from raster data
- Attenuation and min/max range for image layers
- New shader-based geodetic graticule
- New day/night color filter
- Viewpoint: consolidation of look-ats and tethering
- New CoverageSymbol for rastering features into coverage data; agglite driver support
- New feature clustering and instancing algorithms for better performance and scalability
- Noise extension for creating a simplex noise sampler
- New TerrainShader extension lets you inject arbitrary shader code from an earth file
- VirtualProgram: specify all VP injection criteria with GLSL #pragmas
- Normal mapping extension with automatic edge-normalization
- Bump map extension for simple detail bumping
- Performance improvements based on GlowCode profiling results
Version 2.6 (October 2014)¶
Maintenance Release. Release notes TBD.
Version 2.5 (November 2013)¶
Terrain Engine
The terrain engine (“MP”) has undergone many performance updates. We focused on geometry optimization and GL state optimization, bypassing some the OSG mechnisms and going straight to GL to make things as fast as possible.
MP has a new optional “incremental update” feature. By default, when you change the map model (add/remove layers etc.) osgEarth will rebuild the terrain in its entirely. With incremental update enabled, it will only rebuild tiles that are visible. Tiles not currently visible (like those at lower LODs) don’t update until they actually become visible.
Caching
Caching got a couple improvements. The cache seeder (osgearth_cache) is now multi-threaded (as it the TMS packager utility). The filesystem cache also supports expiration policies for cached items, including map tiles.
JavaScript
We updated osgEarth to work with the newest Google V8 JavaScript interpreter API. We also now support JavaScriptCore as a JS interpreter for OSX/iOS devices (where V8 is not available).
Terrain Effects
A new TerrainEffect API makes it easy to add custom shaders to the terrain. osgEarth has several of these built in, including NormalMap, DetailTexture, LODBlending, and ContourMap.
New Drivers
There is a new Bing Maps driver. Bing requires an API key, which you can get at the Bing site.
We also added a new LibNOISE driver. It generates parametric noise that you can use as terrain elevation data, or to add fractal detail to existing terrain, or to generate noise patterns for detail texturing.
Other Goodies
- Shared Layers allow access multiple samplers from a custom shader
- A new “AUTO_SCALE” render bin scales geometry to the screen without using an AutoTransform node.
- PlaceNodes and LabelNodes now support localized occlusion culling.
- The Controls utility library works on iOS/GLES now.
Version 2.4 (April 2013)¶
- New “MP” terrain engine with better performance and support for unlimited image layers (now the default)
- Shader Composition - reworked the framework for more flexible control of vertex shaders
- EarthManipulator - support for mobile (multitouch) actions
- GPU clamping of feature geometry (ClampableNode)
- TMSBackFiller tool to generate low-res LODs from high-res data
- OceanSurface support for masking layer
- New RenderSymbol for draw control
- Fade-in control for feature layers
- OverlayDecorator - improvements in draping; eliminated jittering
- Added feature caching in FeatureSourceIndexNode
- ShaderGenerator - added support for more texture types
- Draping - moved draping/clamping control into Symbology (AltitudeSymbol)
- Lines - add units to “stroke-width”, for values like “25m”, also “stroke-min-pixels”
- PolygonizeLines operator with GPU auto-scaling
- New Documentation site (stored in the repo) at http://osgearth.readthedocs.org
- Decluttering - new “max_objects” property to limit number of drawables
- New ElevationLOD node
- SkyNode - added automatic ambient light calculation
- New DataScanner - build ImageLayers from a recursive file search
- Qt: new ViewWidget for use with a CompositeViewer
- Map: batch updates using the beginUpdate/endUpdate construct
- GLSL Color Filter: embed custom GLSL code directly in the earth file (glsl_filter.earth)
- Agglite: Support for “stroke-width” with units and min-pixels for rasterization
- Terrain options: force an elevation grid size with <elevation_tile_size>
- Better iOS support
- New “BYO” terrain engine lets you load an external model as your terrain
- New “first_lod” property lets you force a minimum LOD to start at
- Better support for tiled data layers
- Lots of bug fixes and performance improvements
- New documentation site stored in the osgEarth repo (docs.osgearth.org)
Upgrading from osgEarth 2.x to osgEarth 3.x¶
The goal for osgEarth 3.x was to make the SDK easier to work with for both developers (writing against the API) and end users (creating earth files). This document serves to help you update existing code and earth files for use with osgEarth 3.x.
The primary objectives of 3.x were:
- Treat everything as a Layer, so that a Map can be a container for almost all data.
- Make all the various Layer types explicit and reduce the dependency on using plug-ins.
- Simplify the API for creating and adding Layers by eschewing the “Options” structure pattern.
- Simplify the approach to making new or custom Layer types.
Earth File Changes¶
Following the idea of downplaying plugin layer types, Layers in an earth file are now explicit. For a GDAL layer in 2.x you would have had something like this:
<image name="My Layer" driver="gdal">
<url>file.tif</url>
</image>
In 3.x the layer type is explicit, like so:
<GDALImage name="My Layer">
<url>file.tif</url>
</GDALImage>
Image and Elevation layer types are still separate, and use explicit types are well. A 3.x GDAL elevation layer looks like:
<GDALElevation name="My DEM">
<url>dem.tif</url>
</GDALElevation>
Here is a partial table mapping old setups to the new 3.x format:
| 2.x | 3.x |
|---|---|
<image driver="gdal"> |
<GDALImage> |
<elevation driver="gdal"> |
<GDALElevation> |
<image driver="tms"> |
<TMSImage> |
<elevation driver="tms"> |
<TMSElevation> |
<image driver="xyz"> |
<XYZImage> |
<elevation driver="xyz"> |
<XYZElevation> |
<image driver="wms"> |
<WMSImage> |
Composite layers¶
Composite layers in 2.x used the “composite” driver in an image or elevation layer. In 3.x there is a new first-class CompositeImage and CompositeElevation types. Here is an example:
<Map>
<CompositeImage name="combined">
<layers>
<TMSImage>
<url>http://readymap.org/readymap/tiles/1.0.0/7/</url>
</TMSImage>
<GDALImage>
<url>locallInset.tif</url>
</GDALImage>
</layers>
</CompositeImage>
</Map>
Feature sources¶
Feature layers (layers containing feature data) are not new to 3.x, but they are also explicit just like the visible layer types above. For example, in osgEarth 2.x you might define a simple feature layer like so:
<feature_model name="states">
<features name="states" driver="ogr">
<url>../data/usa.shp</url>
</features>
<styles>
<style type="text/css">
states {
stroke: #ffff00;
}
</style>
</styles>
</feature_model>
In osgEarth 3.x, the definition (using an embedded feature source) looks like this:
<FeatureModel name="US States">
<OGRFeatures name="US-Data">
<url>../data/usa.shp</url>
</OGRFeatures>
<styles>
<style type="text/css">
states {
stroke:#ffff00;
}
</style>
</styles>
</FeatureModel>
Or, you can define your feature data as a separate Layer and reference it. This way, multiple visible Layers can use the same feature source:
<OGRFeatures name="data:states">
<url>../data/usa.shp</url>
</OGRFeatures>
<FeatureModel name="US States" features="data:states">
<styles>
<style type="text/css">
states {
stroke: #ffff00;
}
</style>
</styles>
</FeatureModel>
Even a stylesheet can be a separate layer now. You can rewrite the same thing above as:
<OGRFeatures name="data:states">
<url>../data/usa.shp</url>
</OGRFeatures>
<Styles name="data:styles">
<style type="text/css">
states {
stroke: #ffff00;
}
</style>
</Styles>
<FeatureModel name="US States" features="data:states" styles="data:styles">
</FeatureModel>
API Changes¶
In 2.x, you created map layers (and various other things) by creating an “Options” structure and then passing that to the constructor of the new Layer. In 3.x you no longer need to do that; you can just create a new Layer and call its setter functions.
Here is an example of creating a WMS image layer in osgEarth 2.x:
#include <osgEarthDrivers/wms/WMSOptions>
...
WMSOptions wms;
wms.url() = "http://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi";
wms.format() = "png";
wms.layers() = "nexrad-n0r";
wms.srs() = "EPSG:4326";
wms.transparent() = true;
ImageLayerOptions wmsLayerOptions("WMS NEXRAD", wms);
wmsLayerOptions.cachePolicy() = CachePolicy::NO_CACHE;
ImageLayer* layer = new ImageLayer(wmsLayerOptions);
map->addLayer(layer);
In 3.x the API is more intuitive, without any intermediate structures:
#include <osgEarth/WMS>
...
WMSImageLayer* wms = new WMSImageLayer();
wms->setURL("http://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi");
wms->setFormat("png");
wms->setLayers("nexrad-n0r");
wms->setSRS("EPSG:4326");
wms->setTransparent(true);
wms->options().cachePolicy() = CachePolicy::NO_CACHE;
map->addLayer(wms);
Follow the same pattern for all layer types. See the osgearth_map.cpp example for several examples.
Getting Support¶
Since osgEarth is a free open source SDK, the code is available to anyone and we welcome and encourage community participation when it comes to testing, adding features, and fixing bugs.
GitHub Repository¶
Use the osgEarth GitHub repository to access the source, download releases, and post bug reports.
Discussion Forum¶
Join the osgEarth Discussion Forum to interact with other users. Please read and follow these guidelines for using the forum. FOLLOWING THESE GUIDELINES will make it MUCH MORE LIKELY that someone will respond and try to help:
- Sign up for an account and use your real name. You can participate anonymously, but using your real name helps build a stronger community. Sign your posts too!
- Limit yourself to one topic per post. Asking multiple questions in one post makes it too hard to keep track of responses.
- Always include as much supporting information as possible. Post an earth file or short code snippet. Post the output to osgearth_version –caps. Post the output to gdalinfo if you are having trouble with a GeoTIFF or other data file. List everything you have tried so far.
- Be patient!
OpenSceneGraph Support¶
osgEarth operates on top of OpenSceneGraph (OSG), an open source 3D rendering toolkit. If you are unable to find answers to your problems on GitHub or in the osgEarth Forum, the OSG Google Group is another place to look.
Professional Services¶
The osgEarth team supports its efforts through professional services. At Pelican Mapping we do custom software development and integration work involving osgEarth (and geospatial technologies in general). We are based in the US but we work with clients all over the world. Contact us if you need help!
License¶
osgEarth is Copyright © Pelican Mapping and licensed under the LGPL free open source license.
This means:
- You can link to the osgEarth SDK in any commercial or non-commercial application free of charge. If you make any changes to osgEarth itself, you must make those changes available as free open source software under the LGPL license. (Typically this means contributing your changes back to the project, but it is sufficient to host them in a public GitHub clone.)
- If you redistribute the osgEarth source code in any form, you must include the associated copyright notices and license information unaltered and intact.
iOS / static linking exception: The LGPL requires that anything statically linked to an LGPL library (like osgEarth) also be released under the LGPL. We grant an exception to the LGPL in this case. If you statically link osgEarth with your proprietary code, you are NOT required to release your own code under the LGPL.
osgEarth is maintained by your friends at Pelican Mapping.